/*
 * Copyright 2002-2020 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.aop.framework;

import org.aopalliance.aop.Advice;

import org.springframework.aop.Advisor;
import org.springframework.aop.TargetClassAware;
import org.springframework.aop.TargetSource;

/**
 * Interface to be implemented by classes that hold the configuration
 * of a factory of AOP proxies. This configuration includes the
 * Interceptors and other advice, Advisors, and the proxied interfaces.
 *
 * <p>Any AOP proxy obtained from Spring can be cast to this interface to
 * allow manipulation of its AOP advice.
 *
 * @author Rod Johnson
 * @author Juergen Hoeller
 * @since 13.03.2003
 * @see org.springframework.aop.framework.AdvisedSupport
 */

/**
 1. 总结
     管理 AOP 代理的配置信息: Advised 是 Spring AOP 框架中的核心配置接口，
	 提供了对代理配置的全面管理功能，包括顾问(Advisor)和通知(Advice)的增删改查操作
	 支持动态修改代理配置，在运行时可以添加、删除或替换 AOP 通知(Advice)和顾问(Advisor)
	 任何 Spring AOP 代理都可以转换为该接口实例进行操作
 2. 内部成员说明
 配置查询方法：
	 boolean isFrozen()：检查配置是否被冻结，冻结后无法修改
	 boolean isProxyTargetClass()：判断是否基于目标类创建代理而非特定接口
	 Class<?>[] getProxiedInterfaces()：获取代理所涉及的接口列表
	 boolean isInterfaceProxied(Class<?> intf)：检查指定接口是否被代理
	 boolean isExposeProxy()：判断是否将代理暴露到 ThreadLocal 中供访问
	 boolean isPreFiltered()：检查顾问是否已经过预过滤
 配置设置方法：
	 void setTargetSource(TargetSource targetSource)：设置目标源
	 void setExposeProxy(boolean exposeProxy)：设置是否暴露代理到 ThreadLocal
	 void setPreFiltered(boolean preFiltered)：设置顾问是否已被预过滤
 顾问管理方法：
	 Advisor[] getAdvisors()：获取所有顾问数组
	 int getAdvisorCount()：获取顾问数量（默认实现）
	 void addAdvisor(Advisor advisor)：在顾问链末尾添加顾问
	 void addAdvisor(int pos, Advisor advisor)：在指定位置添加顾问
	 boolean removeAdvisor(Advisor advisor)：移除指定顾问
	 void removeAdvisor(int index)：根据索引移除顾问
	 int indexOf(Advisor advisor)：查找顾问的位置索引
	 boolean replaceAdvisor(Advisor a, Advisor b)：替换指定顾问
 通知管理方法：
	 void addAdvice(Advice advice)：在通知链末尾添加通知
	 void addAdvice(int pos, Advice advice)：在指定位置添加通知
	 boolean removeAdvice(Advice advice)：移除包含指定通知的顾问
	 int indexOf(Advice advice)：查找包含指定通知的顾问索引
 其他方法：
	 TargetSource getTargetSource()：获取当前的目标源
	 String toProxyConfigString()：返回代理配置的字符串表示
 3. 和其他相关的接口和类

 相关类和接口说明
	 TargetClassAware: 父接口，提供获取目标类的方法
	 AdvisedSupport: Advised 的主要实现类，提供了基础实现
	 ProxyFactoryBean: Spring Bean 方式创建代理的工厂类
	 ProxyFactory: 编程式创建代理的工厂类
	 Advisor: 包含通知和切入点的顾问接口
	 Advice: AOP Alliance 定义的通知接口
	 TargetSource: 目标对象源，控制目标对象的获取

 4. 使用场景
	 动态修改代理配置: 在运行时添加、删除或替换 AOP 通知
	 程序化创建代理: 通过 ProxyFactory 创建代理时配置 AOP 行为
	 自定义代理工厂: 实现自定义的 AOP 代理创建逻辑
	 Spring 内部使用: Spring AOP 框架内部用于管理代理配置
 	 Bean 后处理器：在 Bean 初始化后动态添加切面逻辑

 5. 实际代码应用示例
 =========案例1
 // 在 Bean 后处理器中使用
 public class MyBeanPostProcessor implements BeanPostProcessor {
	 public Object postProcessAfterInitialization(Object bean, String beanName) {
	 if (bean instanceof Advised) {
		 Advised advised = (Advised) bean;
		 // 添加全局的日志通知
		 advised.addAdvice(new LoggingInterceptor());
	 }
	 return bean;
	 }
 }
=============案例2
	 // 创建代理工厂并配置
	 ProxyFactory proxyFactory = new ProxyFactory();
	 proxyFactory.setTarget(myTargetObject);
	 proxyFactory.addAdvice(new MyMethodInterceptor());

	 // 获取并操作 Advised 接口
	 Advised advised = (Advised) proxyFactory.getProxy();
	 System.out.println("Proxy target class: " + advised.getTargetSource().getTargetClass());

	 // 动态添加新的通知
	 advised.addAdvice(new AnotherInterceptor());

	 // 检查代理配置
	 if (!advised.isFrozen()) {
	 advised.addAdvisor(new DefaultPointcutAdvisor(myPointcut, myAdvice));
	 }

	 // 获取所有顾问
	 Advisor[] advisors = advised.getAdvisors();
	 for (Advisor advisor : advisors) {
		System.out.println("Advisor: " + advisor);
	 }




 */
public interface Advised extends TargetClassAware {

	/**
	 * Return whether the Advised configuration is frozen,
	 * in which case no advice changes can be made.
	 */
	boolean isFrozen();

	/**
	 * Are we proxying the full target class instead of specified interfaces?
	 */
	boolean isProxyTargetClass();

	/**
	 * Return the interfaces proxied by the AOP proxy.
	 * <p>Will not include the target class, which may also be proxied.
	 */
	Class<?>[] getProxiedInterfaces();

	/**
	 * Determine whether the given interface is proxied.
	 * @param intf the interface to check
	 */
	boolean isInterfaceProxied(Class<?> intf);

	/**
	 * Change the {@code TargetSource} used by this {@code Advised} object.
	 * <p>Only works if the configuration isn't {@linkplain #isFrozen frozen}.
	 * @param targetSource new TargetSource to use
	 */
	void setTargetSource(TargetSource targetSource);

	/**
	 * Return the {@code TargetSource} used by this {@code Advised} object.
	 */
	TargetSource getTargetSource();

	/**
	 * Set whether the proxy should be exposed by the AOP framework as a
	 * {@link ThreadLocal} for retrieval via the {@link AopContext} class.
	 * <p>It can be necessary to expose the proxy if an advised object needs
	 * to invoke a method on itself with advice applied. Otherwise, if an
	 * advised object invokes a method on {@code this}, no advice will be applied.
	 * <p>Default is {@code false}, for optimal performance.
	 */
	void setExposeProxy(boolean exposeProxy);

	/**
	 * Return whether the factory should expose the proxy as a {@link ThreadLocal}.
	 * <p>It can be necessary to expose the proxy if an advised object needs
	 * to invoke a method on itself with advice applied. Otherwise, if an
	 * advised object invokes a method on {@code this}, no advice will be applied.
	 * <p>Getting the proxy is analogous to an EJB calling {@code getEJBObject()}.
	 * @see AopContext
	 */
	boolean isExposeProxy();

	/**
	 * Set whether this proxy configuration is pre-filtered so that it only
	 * contains applicable advisors (matching this proxy's target class).
	 * <p>Default is "false". Set this to "true" if the advisors have been
	 * pre-filtered already, meaning that the ClassFilter check can be skipped
	 * when building the actual advisor chain for proxy invocations.
	 * @see org.springframework.aop.ClassFilter
	 */
	void setPreFiltered(boolean preFiltered);

	/**
	 * Return whether this proxy configuration is pre-filtered so that it only
	 * contains applicable advisors (matching this proxy's target class).
	 */
	boolean isPreFiltered();

	/**
	 * Return the advisors applying to this proxy.
	 * @return a list of Advisors applying to this proxy (never {@code null})
	 */
	Advisor[] getAdvisors();

	/**
	 * Return the number of advisors applying to this proxy.
	 * <p>The default implementation delegates to {@code getAdvisors().length}.
	 * @since 5.3.1
	 */
	default int getAdvisorCount() {
		return getAdvisors().length;
	}

	/**
	 * Add an advisor at the end of the advisor chain.
	 * <p>The Advisor may be an {@link org.springframework.aop.IntroductionAdvisor},
	 * in which new interfaces will be available when a proxy is next obtained
	 * from the relevant factory.
	 * @param advisor the advisor to add to the end of the chain
	 * @throws AopConfigException in case of invalid advice
	 */
	void addAdvisor(Advisor advisor) throws AopConfigException;

	/**
	 * Add an Advisor at the specified position in the chain.
	 * @param advisor the advisor to add at the specified position in the chain
	 * @param pos position in chain (0 is head). Must be valid.
	 * @throws AopConfigException in case of invalid advice
	 */
	void addAdvisor(int pos, Advisor advisor) throws AopConfigException;

	/**
	 * Remove the given advisor.
	 * @param advisor the advisor to remove
	 * @return {@code true} if the advisor was removed; {@code false}
	 * if the advisor was not found and hence could not be removed
	 */
	boolean removeAdvisor(Advisor advisor);

	/**
	 * Remove the advisor at the given index.
	 * @param index the index of advisor to remove
	 * @throws AopConfigException if the index is invalid
	 */
	void removeAdvisor(int index) throws AopConfigException;

	/**
	 * Return the index (from 0) of the given advisor,
	 * or -1 if no such advisor applies to this proxy.
	 * <p>The return value of this method can be used to index into the advisors array.
	 * @param advisor the advisor to search for
	 * @return index from 0 of this advisor, or -1 if there's no such advisor
	 */
	int indexOf(Advisor advisor);

	/**
	 * Replace the given advisor.
	 * <p><b>Note:</b> If the advisor is an {@link org.springframework.aop.IntroductionAdvisor}
	 * and the replacement is not or implements different interfaces, the proxy will need
	 * to be re-obtained or the old interfaces won't be supported and the new interface
	 * won't be implemented.
	 * @param a the advisor to replace
	 * @param b the advisor to replace it with
	 * @return whether it was replaced. If the advisor wasn't found in the
	 * list of advisors, this method returns {@code false} and does nothing.
	 * @throws AopConfigException in case of invalid advice
	 */
	boolean replaceAdvisor(Advisor a, Advisor b) throws AopConfigException;

	/**
	 * Add the given AOP Alliance advice to the tail of the advice (interceptor) chain.
	 * <p>This will be wrapped in a DefaultPointcutAdvisor with a pointcut that always
	 * applies, and returned from the {@code getAdvisors()} method in this wrapped form.
	 * <p>Note that the given advice will apply to all invocations on the proxy,
	 * even to the {@code toString()} method! Use appropriate advice implementations
	 * or specify appropriate pointcuts to apply to a narrower set of methods.
	 * @param advice the advice to add to the tail of the chain
	 * @throws AopConfigException in case of invalid advice
	 * @see #addAdvice(int, Advice)
	 * @see org.springframework.aop.support.DefaultPointcutAdvisor
	 */
	void addAdvice(Advice advice) throws AopConfigException;

	/**
	 * Add the given AOP Alliance Advice at the specified position in the advice chain.
	 * <p>This will be wrapped in a {@link org.springframework.aop.support.DefaultPointcutAdvisor}
	 * with a pointcut that always applies, and returned from the {@link #getAdvisors()}
	 * method in this wrapped form.
	 * <p>Note: The given advice will apply to all invocations on the proxy,
	 * even to the {@code toString()} method! Use appropriate advice implementations
	 * or specify appropriate pointcuts to apply to a narrower set of methods.
	 * @param pos index from 0 (head)
	 * @param advice the advice to add at the specified position in the advice chain
	 * @throws AopConfigException in case of invalid advice
	 */
	void addAdvice(int pos, Advice advice) throws AopConfigException;

	/**
	 * Remove the Advisor containing the given advice.
	 * @param advice the advice to remove
	 * @return {@code true} of the advice was found and removed;
	 * {@code false} if there was no such advice
	 */
	boolean removeAdvice(Advice advice);

	/**
	 * Return the index (from 0) of the given AOP Alliance Advice,
	 * or -1 if no such advice is an advice for this proxy.
	 * <p>The return value of this method can be used to index into
	 * the advisors array.
	 * @param advice the AOP Alliance advice to search for
	 * @return index from 0 of this advice, or -1 if there's no such advice
	 */
	int indexOf(Advice advice);

	/**
	 * As {@code toString()} will normally be delegated to the target,
	 * this returns the equivalent for the AOP proxy.
	 * @return a string description of the proxy configuration
	 */
	String toProxyConfigString();

}
